鐵人季後賽《14 天搞定 MACI 實戰部署：從 0 到可重現的 QF 投票系統》

Day 0：系列簡介篇 — 為什麼要挑戰 MACI？

前言：從「透明」到「隱私」的下一步

在區塊鏈世界，我們談透明、談公開、談信任。
但當我們進入治理與投票的場景時，過度透明反而成了風險。
誰投給誰、誰支持哪個提案，如果全部攤在鏈上，
社群投票將不再是自由的，而會被人際或資金壓力左右。

這正是 MACI（Minimal Anti-Collusion Infrastructure） 的初衷。
它讓人們可以在隱私與可驗證之間取得平衡，
實現「誠實最便宜」的投票制度。

MACI 的價值與現實

MACI 是以零知識證明為基礎的投票基礎設施，
它是 Gitcoin Grants、clr.fund、ZK-DAO 等平台的核心理念。
理論上只要幾個步驟就能部署；
但實際上，從 MACI 從 1.0 後，部署難度堪稱 Web3 惡名昭彰。

為什麼這麼多人卡在 MACI？

雖然 MACI 的設計極其優雅，但現實是：

• monorepo 架構龐大，跨多層依賴（contracts、circuits、sdk、cli）
• relayer、coordinator、poll 合約之間關係晦澀
• 官方文件簡短
• 錯誤訊息含糊
  ...

結果是——即使是有經驗的 Web3 開發者，也常常：

• poseidon hash build 失敗
• CLI 或 relayer 無法啟動
• Verifier 無法驗證 proof
  ...

照官方文件走不到十步，幾乎必踩坑。

本系列的定位：理論輕，實戰重

這個 14 天系列不是學術探討，也不是理論講解，
而是一場「從坑裡走出來」的部署實錄。

我們會：

1. 在乾淨環境（WSL2 / macOS）重新建立可重現專案；
2. 分析 MACI monorepo 架構與相依；
3. 一步步部署 circuits、contracts、coordinator、relayer；
4. 驗證投票流程能實際運作；
5. 讓整個系統「跑得起來、能重現、可驗證」。

系列規劃（14 天版）

重點放在部署，後半段簡化整合。

你會學到什麼

• 理解 MACI monorepo 的實際架構
• 建立乾淨環境並避開版本衝突
• 從零生成 circuits 與 verifier
• 成功部署完整投票合約組
• 理解 relayer 與 zk pipeline 的實際運作
• 建立可重現 MACI 專案模板

為什麼是「季後賽」？

因為這已不是新手挑戰，而是經驗者的生死局。
部署 MACI 的過程比一般鐵人賽更長、更曲折，
你會在這裡遇見 Hardhat、circom、pnpm、zkey、verifier、typescript 的全部坑。

這是一場「理解」與「重現」的比賽。
不求炫技，只求真正讓 MACI 起得來。

結語

MACI 是一座由零知識搭起的信任橋樑。
它的價值不在於理論，而在於被成功重現的那一刻。

接下來，讓我們從 Day 1：建立乾淨環境與基礎工具鏈 開始，
一起踏上這條部署之路。

“In theory, there is no difference between theory and practice.
But in practice, there is.”
— Yogi Berra